Usenet 1993 July/InfoMagic USENET CD-ROM July 1993.ISO/sources/misc/volume7/dbug-man

Text File | 1989-07-21 | 17.1 KB | 615 lines

Newsgroups: comp.sources.misc
subject: v07i098: Man pages for DBUG package
from: [e-mail] (Brandon S. Allbery - comp.sources.misc)
Reply-To: [e-mail] (Thomas Oeser)

Posting-number: Volume 7, Issue 98
Submitted-by: [e-mail] (Thomas Oeser)
Archive-name: dbug-man

[[Note:  these are neither a patch to nor an official part of the DBUG
  package.  ++bsa]]

enclosed you find two man pages for the recently distributed DBUG package.
I've picked up some information found in the source files and user's
documentation and put them together to the man pages.

I hope this is a start to make a more complete and accurate version of them.

Thomas Oeser
------------------------------------------------------------------------------
ARPA:        [e-mail]
UUCP:        [e-mail] (may work only in Europe...)
Postal mail:    Siemens AG, K Sys Ap 121, Otto-Hahn-Ring 6, P.O. Box 830951,
        D-8000 Munich 83, West Germany
Phone:        + 49 (89) 636-47537
FAX:        + 49 (89) 636-41477

Disclaimer:
The opinions expressed are my own, and should not be attributed to anyone else
living or dead.
------------------------------------------------------------------------------


#---------- cut here ---------- cut here ----------- cut here -----------------
#! /bin/sh
# This is a shell archive.  Remove anything before this line, then feed it
# into a shell via "sh file" or similar.  To overwrite existing files,
# type "sh file -c".
# The tool that generated this appeared in the comp.sources.unix newsgroup;
# send mail to [e-mail] if you want that tool.
# If this archive is complete, you will see the following message at the end:
#        "End of shell archive."
# Contents:  analyze.man dbug.man
# Wrapped by email@perlach on Thu Jul 20 09:10:09 1989
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'analyze.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'analyze.man'\"
else
echo shar: Extracting \"'analyze.man'\" \(1714 characters\)
sed "s/^X//" >'analyze.man' <<'END_OF_FILE'
X.\" SCCSID = @(#)analyze.man    1.1
X.\"
X.TH ANALYZE 1L "89/07/20" "K Sys Ap 121"
X.SH NAME
Xanalyze \- analyzes the profile file written out by the dbug
Xroutines with profiling enabled.
X.SH SYNOPSIS
X\fIanalyze\fP [-v] [profileFile]
X.ad
X.SH DESCRIPTION
X\fIAnalyze\fP will read an trace file created by the dbug package
X(when run with traceing enabled).  It will then produce a
Xsummary on standard output listing the name of each traced
Xfunction, the number of times it was called, the percentage
Xof total calls, the time spent executing the function, the
Xproportion of the total time and the 'importance'.  The last
Xis a metric which is obtained by multiplying the proportions
Xof calls and the proportions of time for each function.  The
Xgreater the importance, the more likely it is that a speedup
Xcould be obtained by reducing the time taken by that function.
X.PP
XNote that the timing values that you obtain are only rough
Xmeasures.  The overhead of the dbug package is included
Xwithin.  However, there is no need to link in special profiled
Xlibraries and the like.
X.SH OPTIONS
X\fIAnnalize\fP accepts the following command line options:
X.TP 16
X-v
XIf this option is specified, the output of this program will be a verbose
Xtable. By default, the output of this program will look very similar to
XUnix profiler.
X.TP 16
XprofileFile
XSpecifies the the name of file containing the input data to be examined
X(default: dbugmon.out).
X.SH USAGE
XThis should be easy :-).
X.SH FILES
Xdbugmon.out
X.SH "SEE ALSO"
Xdbug(3L)
X.SH ENVIRONMENT
Xnone
X.SH BUGS
XThere still are some.
X.SH COPYRIGHT
Xnone
X.SH AUTHORS
XFred Fish, Binayak Banerjee
X.br
XEnhanced Software Technologies, Tempe, AZ
X.br
Xasuvax!mcdphx!estinc!fnf, seismo!bpa!sjuvax!bbanerje

END_OF_FILE
echo shar: NEWLINE appended to \"'analyze.man'\"
if test 1715 -ne `wc -c <'analyze.man'`; then
    echo shar: \"'analyze.man'\" unpacked with wrong size!
fi
# end of 'analyze.man'
fi
if test -f 'dbug.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'dbug.man'\"
else
echo shar: Extracting \"'dbug.man'\" \(12580 characters\)
sed "s/^X//" >'dbug.man' <<'END_OF_FILE'
X.\" SCCSID = @(#)dbug.man    1.1
X.\"
X.TH DBUG 3L "89/07/20" "K Sys Ap 121"
X.SH NAME
Xdbug \- a toolset for internal debugging of C programs.
X.ad
X.SH SYNOPSIS
XNote, the following "functions" are C macros. Therefore, the description of
Xthe parameters are not necessarily correct C. The intention is, to describe as
Xclose as possible but shortly what type of "data" can be used for the
Xparameters of the macros.
X.PP
X#include <dbug.h>
X.PP
X\fIDBUG_ENTER\fP ( aName )
X.RS 6
Xchar *    aName;
X.RS -6
X.PP
X\fIDBUG_RETURN\fP ( aValue )
X.RS 6
Xint    aValue;
X.RS -6
X.PP
X\fIDBUG_VOID_RETURN\fP
X.PP
X\fIDBUG_PRINT\fP ( aLabelString, (thePrintfParameters) )
X.RS 6
Xchar *    aLabelString;
X.br
XParameterList thePrintfParameters;
X.RS -6
X.PP
X\fIDBUG_PROCESS\fP ( aName )
X.RS 6
Xchar *    aName;
X.RS -6
X.PP
X\fIDBUG_PUSH\fP ( aDbugOptionString )
X.RS 6
Xchar *    aDbugOptionString;
X.RS -6
X.PP
X\fIDBUG_POP\fP ()
X.PP
X\fIDBUG_FILE\fP
X.PP
X\fIDBUG_EXECUTE\fP ( aLabelString, someCode )
X.RS 6
Xchar *    aLabelString;
X.br
XC-Code    someCode;
X.RS -6
X.PP
X\fIDBUG_SETJMP\fP ( env )
X.RS 6
Xjmp_buf    env;
X.RS -6
X.PP
X\fIDBUG_LONGJMP\fP ( env, val )
X.RS 6
Xjmp_buf    env;
X.br
Xint    val;
X.RS -6
X.SH DESCRIPTION
X\fIDbug\fP is
Xa macro based C internal debugging
Xpackage which has proven to be a very flexible and useful tool
Xfor debugging, testing, and porting C programs.
X.PP
XInternal debugging are typically "print statements" included into the program
Xsource. \fIDbug\fP provides for enhanced capabilities to do so. In addition
Xeach capability can be individually enabled or disabled at the time a program
Xis invoked by specifying the appropriate command line arguments.
X.PP
XSo, all of the features of the
X.I dbug
Xpackage can be enabled or disabled dynamically at execution time.
XThis means that production programs will run normally when
Xdebugging is not enabled, and eliminates the need to maintain two
Xseparate versions of a program.
X.PP
XThe following specifies a summary of the \fIdbug\fP capabilities:
X.TP 3
X-
XExecution trace showing function level control flow in a
Xsemi-graphically manner using indentation to indicate nesting
Xdepth.
X.TP 3
X-
XOutput the values of all, or any subset of, key internal variables.
X.TP 3
X-
XLimit actions to a specific set of named functions.
X.TP 3
X-
XLimit function trace to a specified nesting depth.
X.TP 3
X-
XLabel each output line with source file name and line number.
X.TP 3
X-
XLabel each output line with name of current process.
X.TP 3
X-
XPush or pop internal debugging state to allow execution with
Xbuilt in debugging defaults.
X.TP 3
X-
XRedirect the debug output stream to standard output (stdout)
Xor a named file.
XThe default output stream is standard error (stderr).
X.PP
XMany of the things easily accomplished with conventional debugging
Xtools, such as symbolic debuggers, are difficult or impossible with this
Xpackage, and vice versa.
XThus the
X.I dbug
Xpackage should
X.I not
Xbe thought of as a replacement or substitute for
Xother debugging tools, but simply as a useful
X.I addition
Xto the
Xprogram development and maintenance environment.
X.PP
XThe
X.I dbug
Xpackage imposes only a slight speed penalty on executing
Xprograms, typically much less than 10 percent, and a modest size
Xpenalty, typically 10 to 20 percent.
XBy defining a specific C preprocessor symbol both of these
Xcan be reduced to zero with no changes required to the
Xsource code.
X.PP
XNotice, that all of the debugger functions are implemented
Xvia preprocessor macros.
XThis does not detract from the readability of the code and makes disabling
Xall debug compilation trivial (a single preprocessor symbol,
X.B DBUG_OFF ,
Xforces the macro expansions to be null).
X.SH "SUMMARY OF MACROS"
XThis summarizes the usage of all currently defined macros
Xin the
X.I dbug
Xpackage.
XThe macros definitions are found in the user include file
X.B dbug.h
Xfrom the standard include directory.
X.TP 15
XDBUG_ENTER
XUsed to tell the runtime support module the name of the function
Xbeing entered.
XThe argument must be of type "pointer to character".
XThe
XDBUG_ENTER
Xmacro must precede all executable lines in the
Xfunction just entered, and must come after all local declarations.
XEach
XDBUG_ENTER
Xmacro must have a matching
XDBUG_RETURN
Xor
XDBUG_VOID_RETURN
Xmacro
Xat the function exit points.
XDBUG_ENTER
Xmacros used without a matching
XDBUG_RETURN
Xor
XDBUG_VOID_RETURN
Xmacro
Xwill cause warning messages from the
X.I dbug
Xpackage runtime support module.
X.br
X.sp
XEX:\ DBUG_ENTER\ ("main");
X.TP 15
XDBUG_RETURN
XUsed at each exit point of a function containing a
XDBUG_ENTER
Xmacro
Xat the entry point.
XThe argument is the value to return.
XFunctions which return no value (void) should use the
XDBUG_VOID_RETURN
Xmacro.
XIt
Xis an error to have a
XDBUG_RETURN
Xor
XDBUG_VOID_RETURN
Xmacro in a function
Xwhich has no matching
XDBUG_ENTER
Xmacro, and the compiler will complain
Xif the macros are actually used (expanded).
X.br
X.sp
XEX:\ DBUG_RETURN\ (value);
X.br
XEX:\ DBUG_VOID_RETURN;
X.TP 15
XDBUG_PROCESS
XUsed to name the current process being executed.
XA typical argument for this macro is "argv[0]", though
Xit will be perfectly happy with any other string.
X.br
X.sp
XEX:\ DBUG_PROCESS\ (argv[0]);
X.TP 15
XDBUG_PUSH
XSets a new debugger state by pushing the current
X.B dbug
Xstate onto an
Xinternal stack and setting up the new state using the debug control
Xstring passed as the macro argument.
XThe most common usage is to set the state specified by a debug
Xcontrol string retrieved from the argument list.
XNote that the leading "\-#" in a debug control string specified
Xas a command line argument must
X.B not
Xbe passed as part of the macro argument.
XThe proper usage is to pass a pointer to the first character
X.B after
Xthe "\-#" string.
X.br
X.sp
XEX:\ DBUG_PUSH\ (\&(argv[i][2]));
X.br
XEX:\ DBUG_PUSH\ ("d:t");
X.br
XEX:\ DBUG_PUSH\ (" ");
X.TP 15
XDBUG_POP
XRestores the previous debugger state by popping the state stack.
XAttempting to pop more states than pushed will be ignored and no
Xwarning will be given.
XThe
XDBUG_POP
Xmacro has no arguments.
X.br
X.sp
XEX:\ DBUG_POP\ ();
X.TP 15
XDBUG_FILE
XThe
XDBUG_FILE
Xmacro is used to do explicit I/O on the debug output
Xstream.
XIt is used in the same manner as the symbols "stdout" and "stderr"
Xin the standard I/O package.
X.br
X.sp
XEX:\ fprintf\ (DBUG_FILE,\ "Doing\ my\ own\ I/O!\\n");
X.TP 15
XDBUG_EXECUTE
XThe DBUG_EXECUTE macro is used to execute any arbitrary C code.
XThe first argument is the debug keyword, used to trigger execution
Xof the code specified as the second argument.
XThis macro must be used cautiously because, like the
XDBUG_PRINT
Xmacro,
Xit is automatically selected by default whenever the 'd' flag has
Xno argument list (I.E., a "\-#d:t" control string).
X.br
X.sp
XEX:\ DBUG_EXECUTE\ ("abort",\ abort\ ());
X.TP 15
XDBUG_N
XThese macros, where N is in the range 2\-5, are currently obsolete
Xand will be removed in a future release.
XUse the new DBUG_PRINT macro.
X.TP 15
XDBUG_PRINT
XUsed to do printing via the "fprintf" library function on the
Xcurrent debug stream,
XDBUG_FILE.
XThe first argument is a debug keyword, the second is a format string
Xand the corresponding argument list.
XNote that the format string and argument list are all one macro argument
Xand
X.B must
Xbe enclosed in parenthesis.
X.br
X.sp
XEX:\ DBUG_PRINT\ ("eof",\ ("end\ of\ file\ found"));
X.br
XEX:\ DBUG_PRINT\ ("type",\ ("type\ is\ %x",\ type));
X.br
XEX:\ DBUG_PRINT\ ("stp",\ ("%x\ \->\ %s",\ stp,\ stp\ \->\ name));
X.TP 15
XDBUG_SETJMP
XUsed in place of the setjmp() function to first save the current
Xdebugger state and then execute the standard setjmp call.
XThis allows the debugger to restore its state when the
XDBUG_LONGJMP macro is used to invoke the standard longjmp() call.
XCurrently all instances of DBUG_SETJMP must occur within the
Xsame function and at the same function nesting level.
X.br
X.sp
XEX:\ DBUG_SETJMP\ (env);
X.TP 15
XDBUG_LONGJMP
XUsed in place of the longjmp() function to first restore the
Xprevious debugger state at the time of the last DBUG_SETJMP
Xand then execute the standard longjmp() call.
XNote that currently all DBUG_LONGJMP macros restore the state
Xat the time of the last DBUG_SETJMP.
XIt would be possible to maintain separate DBUG_SETJMP and DBUG_LONGJMP
Xpairs by having the debugger runtime support module use the first
Xargument to differentiate the pairs.
X.br
X.sp
XEX:\ DBUG_LONGJMP\ (env,val);
X.SH "DEBUG CONTROL STRING"
XThe debug control string is used to control the "behaviour" of the dbug macros,
Xwhen running the application. The \fIdebug control string\fP is passed to the
X\fIdbug\fP package via the \fIDBUG_PUSH()\fP macro (note, that the parameter of
Xthis macro may be the value of a program argument; see example above).
X.PP
XThe following list summarizes the currently available debugger options
Xand the flag characters which enable or disable them. Debugger options may be
Xconcatenated to a \fIdebug control string\fP using the ":" (colon) as a
Xseperator (e.g., <option1>:<option2>:...:<optionN>).
X.PP
XArgument lists enclosed in '[' and ']' are optional.
X.TP 15
Xd[,keywords]
XEnable output from macros with specified keywords.
XA null list of keywords implies that all keywords are selected.
X.TP 15
XD[,time]
XDelay for specified time after each output line, to let output drain.
XTime is given in tenths of a second (value of 10 is one second).
XDefault is zero.
X.TP 15
Xf[,functions]
XLimit debugger actions to the specified list of functions.
XA null list of functions implies that all functions are selected.
X.TP 15
XF
XMark each debugger output line with the name of the source file
Xcontaining the macro causing the output.
X.TP 15
Xg
XTurn on machine independent profiling.
XA profiling data collection file, named dbugmon.out, will be written
Xfor postprocessing by the "analyze(1L)" program.
XThe accuracy of this feature is relatively unknown at this time.
X.TP 15
Xi
XIdentify the process emitting each line of debug or trace output
Xwith the process id for that process.
X.TP 15
XL
XMark each debugger output line with the source file line number of
Xthe macro causing the output.
X.TP 15
Xn
XMark each debugger output line with the current function nesting depth.
X.TP 15
XN
XSequentially number each debugger output line starting at 1.
XThis is useful for reference purposes when debugger output is
Xinterspersed with program output.
X.TP 15
Xo[,file]
XRedirect the debugger output stream to the specified file.
XThe default output stream is stderr.
XA null argument list causes output to be redirected to stdout.
X.TP 15
Xp[,processes]
XLimit debugger actions to the specified processes.
XA null list implies all processes.
XThis is useful for processes which run child processes.
XNote that each debugger output line can be marked with the name of
Xthe current process via the 'P' flag.
XThe process name must match the argument passed to the
X.B DBUG_PROCESS
Xmacro.
X.TP 15
XP
XMark each debugger output line with the name of the current process
Xfrom argv[0].
XMost useful when used with a process which runs child processes that
Xare also being debugged.
XNote that the parent process must arrange for the debugger control
Xstring to be passed to the child processes.
X.TP 15
Xr
XUsed in conjunction with the
X.B DBUG_PUSH
Xmacro to reset the current
Xindentation level back to zero.
XMost useful with
X.B DBUG_PUSH
Xmacros used to temporarily alter the
Xdebugger state.
X.TP 15
Xt[,N]
XEnable function control flow tracing.
XThe maximum nesting depth is specified by N, and defaults to
X200.
X.SH USAGE
XThe following example shows a very simple use of the \fIdbug\fP facilities.
X.PP
XFirst, the source code including some \fIdbug\fP statements is given:
X.RS 12
X.sp
X.nf
X#include <stdio.h>
X#include <dbug.h>
X
Xmain (argc, argv)
Xint argc;
Xchar *argv[];
X{
X    int i;
X    int atoi();
X
X    DBUG_ENTER ("main");
X    DBUG_PROCESS (argv[0]);
X
X    for (i = 1; i < argc && argv[i][0] == '-'; i++) {
X    switch (argv[i][1]) {
X        case '#':
X        DBUG_PUSH (&(argv[i][2]));
X        break;
X    }
X    }
X
X    for (; i < argc; i++) {
X    DBUG_PRINT ("args", ("argv[%d] = %s", i, argv[i]));
X    printf ("%F\\n", 1.0/atoi(argv[i]));
X    }
X
X    DBUG_RETURN (0);
X}
X.fi
X.sp
X.RS -12
X.PP
XThe following invocation of the program "inverse" compiled from the source
Xabove would cause the corresponding outputs:
X.RS 12
X.sp
X.nf
X$ inverse\ \ 2 4
X0.5
X0.25
X
X$ inverse -#t\ \ 2 4
X|
X0.5
X0.25
X< main
X
Xinverse -#d:t\ \ 2 4
X| args: argv[2] = 2
X0.5
X| args: argv[3] = 4
X0.25
X< main
X.fi
X.sp
X.RS -12
X.SH FILES
X/LocalTools/lib/local/libdbug.a
X/LocalTools/include/local/dbug.h
X.SH "SEE ALSO"
XDBUG Users Manual, analyze(1L)
X.SH ENVIRONMENT
Xnone
X.SH BUGS
XThere still are some.
X.SH COPYRIGHT
Xnone
X.SH AUTHORS
XFred Fish, Binayak Banerjee
X.br
XEnhanced Software Technologies, Tempe, AZ
X.br
Xasuvax!mcdphx!estinc!fnf, seismo!bpa!sjuvax!bbanerje

END_OF_FILE
echo shar: NEWLINE appended to \"'dbug.man'\"
if test 12581 -ne `wc -c <'dbug.man'`; then
    echo shar: \"'dbug.man'\" unpacked with wrong size!
fi
# end of 'dbug.man'
fi
echo shar: End of shell archive.
exit 0